﻿using RJi.FanucInterface3.Common.Enum;

namespace RJi.FanucInterface3.Common;

public interface IDataTableWrapper
{
    /// <summary>
    ///     注册机器人报警历史记录到数据表
    /// </summary>
    /// <param name="count">读取的报警记录数量（例如最近100条报警）</param>
    /// <param name="key">数据表关联的键名，默认"ALARM_LIST"</param>
    /// <returns>包装后的数据表对象，包含报警代码、时间戳等信息</returns>
    /// <remarks>
    ///     示例：RegisterAlarmHistory(50) 获取最近50条报警记录
    /// </remarks>
    IDataTableWrapper RegisterAlarmHistory(int count, string key = "ALARM_LIST");

    /// <summary>
    ///     注册机器人当前关节/直角坐标位置到数据表（基于机械坐标系）
    /// </summary>
    /// <param name="group">机器人运动组编号，默认 1（主组）</param>
    /// <param name="key">数据表关联的键名，默认 "CUR_POS"</param>
    /// <returns>包装后的数据表对象，包含 X/Y/Z 和姿态数据</returns>
    /// <remarks>
    ///     适用于示教或运动轨迹监控场景
    /// </remarks>
    IDataTableWrapper RegisterCurPos(int group = 1, string key = "CUR_POS");

    /// <summary>
    ///     注册机器人当前位姿到数据表（基于用户自定义坐标系）
    /// </summary>
    /// <param name="userFrame">用户坐标系编号（如夹具坐标系）</param>
    /// <param name="group">机器人运动组编号，默认 1</param>
    /// <param name="key">数据表关联的键名，默认 "CUR_POS_USER_FRAME"</param>
    /// <returns>包装后的数据表对象，坐标已转换到用户坐标系</returns>
    /// <remarks>
    ///     示例：RegisterCurPosWithUserFrame(2) 获取在用户坐标系 2 下的当前位置
    /// </remarks>
    IDataTableWrapper RegisterCurPosWithUserFrame(int userFrame = 1, int group = 1, string key = "CUR_POS_USER_FRAME");

    /// <summary>
    ///     注册数字寄存器到数据表
    /// </summary>
    /// <param name="startIndex">寄存器起始索引（从 1 开始）</param>
    /// <param name="endIndex">寄存器结束索引</param>
    /// <param name="key">数据表关联的键名，默认"NUM_REG"</param>
    /// <returns>包装后的数据表对象，按索引顺序存储寄存器值</returns>
    /// <remarks>
    ///     示例：RegisterNumReg(1, 10) 监控 R[1] 到 R[10] 的数值
    /// </remarks>
    IDataTableWrapper RegisterNumReg(int startIndex, int endIndex, string key = "NUM_REG");

    /// <summary>
    ///     批量注册位置寄存器（如 PR[1]-PR[10]）到数据表
    /// </summary>
    /// <param name="startIndex">起始寄存器索引</param>
    /// <param name="endIndex">寄存器结束索引</param>
    /// <param name="group">运动组编号，默认 1</param>
    /// <param name="key">数据表关联的键名，默认"POS_REG"</param>
    /// <returns>包装后的数据表对象，包含 XYZWPR 格式的位置数据</returns>
    /// <remarks>
    ///     示例：RegisterPosReg(2，5) 获取 PR[2]-PR[5] 坐标
    /// </remarks>
    IDataTableWrapper RegisterPosReg(int startIndex, int endIndex, int group = 1, string key = "POS_REG");

    /// <summary>
    ///     批量注册位置寄存器的卡迪尔坐标（如 PR[1]-PR[10]）到数据表,用于写入寄存器
    /// </summary>
    /// <param name="startIndex">起始寄存器索引</param>
    /// <param name="endIndex">寄存器结束索引</param>
    /// <param name="group">运动组编号，默认 1</param>
    /// <param name="key">数据表关联的键名，默认 "POS_REG_CARTESIAN"</param>
    /// <returns>包装后的数据表对象，包含卡迪尔格式的位置数据</returns>
    /// ///
    /// <remarks>
    ///     示例：RegisterPosRegCartesian(2，5) 获取 PR[2]-PR[5]的卡迪尔坐标
    /// </remarks>
    IDataTableWrapper RegisterPosRegCartesian(int startIndex, int endIndex, int group = 1, string key = "POS_REG_CARTESIAN");

    /// <summary>
    ///     批量注册多运动组位置寄存器（如 PR[1]-PR[10]）到数据表，支持混合坐标系（笛卡尔/关节）,用于写入寄存器
    /// </summary>
    /// <param name="startIndex">起始寄存器索引</param>
    /// <param name="endIndex">寄存器结束索引</param>
    /// <param name="motionGroups">运动组坐标系定义字符串（逗号分隔，"C"=笛卡尔，"J#"=关节轴）</param>
    /// <param name="key">数据表关联的键名，默认 "POS_REG_MG"</param>
    /// <returns>包装后的数据表对象，包含卡迪尔格式的位置数据</returns>
    /// ///
    /// <remarks>
    ///     示例：RegisterPosRegMultipleGroup(2，5,"C,J1,J1,J1,J1") 获取PR[2]-PR[5] 运动组1为笛卡尔，运动组2-5为关节轴1
    /// </remarks>
    IDataTableWrapper RegisterPosRegMultipleGroup(int startIndex, int endIndex, string motionGroups = "C,J6", string key = "POS_REG_MG");

    /// <summary>
    ///     注册寄存器的注释
    /// </summary>
    /// <param name="startIndex">起始寄存器索引</param>
    /// <param name="endIndex">寄存器结束索引</param>
    /// <param name="commentType">寄存器类型</param>
    /// <param name="key">数据表关联的键名，默认 null </param>
    /// <returns>包装后的数据表对象</returns>
    IDataTableWrapper RegisterRegComment(int startIndex, int endIndex, RegCommentType commentType, string? key = null);

    /// <summary>
    ///     注册字符串寄存器到数据表
    /// </summary>
    /// <param name="startIndex">寄存器起始索引（从 1 开始）</param>
    /// <param name="endIndex">寄存器结束索引</param>
    /// <param name="key">数据表关联的键名，默认 "STRING_REG"</param>
    /// <returns>包装后的数据表对象，按索引顺序存储寄存器值</returns>
    /// <remarks>
    ///     示例：RegisterStringReg(1, 10) 监控 SR[1] 到 SR[10] 的数值
    /// </remarks>
    IDataTableWrapper RegisterStringReg(int startIndex, int endIndex, string key = "STRING_REG");

    /// <summary>
    ///     注册单个系统变量（如 $MODE 或 $FAST_CLOCK）到数据表
    /// </summary>
    /// <param name="sysVarName">变量名（需包含 $ 前缀）</param>
    /// <param name="varType">系统变量的数据类型，默认使用 Real</param>
    /// <param name="key">数据表关联的键名，默认使用变量名</param>
    /// <returns>包装后的数据表对象，支持整数/浮点/字符串/位置类型</returns>
    /// <remarks>
    ///     示例：RegisterSysVar("$MODE") 监控机器人运行模式
    /// </remarks>
    IDataTableWrapper RegisterSysVar(string sysVarName, SysVarType varType = SysVarType.Real, string? key = null);

    /// <summary>
    ///     批量注册相同数据类型的系统变量到数据表，用于系统变量数组的注册
    /// </summary>
    /// <param name="key">数据表关联的键名</param>
    /// <param name="sysVarNames">变量名数组</param>
    /// <param name="varType">系统变量的数据类型，默认使用 Real</param>
    /// <returns>包装后的数据表对象，按输入顺序存储变量值，支持整数/浮点/字符串/位置类型</returns>
    /// <remarks>
    ///     适用于多变量联合监控场景
    /// </remarks>
    IDataTableWrapper RegisterSysVars(string key, SysVarType varType = SysVarType.Real, params string[] sysVarNames);

    /// <summary>
    ///     注册机器人任务执行状态到数据表，用于监控程序执行状态（程序名、行号等）。
    /// </summary>
    /// <param name="index">
    ///     任务编号（多任务系统中，1=第一个任务，2=第二个任务）。
    ///     任务在执行过程中会保持其编号。
    /// </param>
    /// <param name="varType">
    ///     注册的数据类型，决定是否忽略宏程序或KAREL程序：
    ///     - TaskVarType.Task (4): 返回当前执行程序名和行号
    ///     - TaskVarType.IgnoreMacro (33): 如果是宏程序，返回调用者程序信息
    ///     - TaskVarType.IgnoreKarel (34): 如果是KAREL程序，返回调用者程序信息
    ///     - TaskVarType.IgnoreMacroKarel (35): 如果是宏或KAREL程序，返回调用者程序信息
    /// </param>
    /// <param name="key">数据表关联的键名，默认"TASK"</param>
    /// <returns>
    ///     成功返回 DataTask 包装对象（可用于读取程序执行状态），失败返回 null。
    /// </returns>
    /// <remarks>
    ///     <para>功能说明：</para>
    ///     <list type="bullet">
    ///         <item>监控机器人当前执行的程序名和行号</item>
    ///         <item>支持多任务系统（通过 index 指定任务编号）</item>
    ///     </list>
    ///     <para>使用示例：</para>
    ///     <code>
    ///         var taskMonitor = RegisterTask(1); // 监控任务1
    ///         var taskMonitorIgnoreMacro = RegisterTask(1, TaskVarType.IgnoreMacro); // 忽略宏程序
    ///     </code>
    ///     <para>兼容性说明：</para>
    ///     <list type="bullet">
    ///         <item>仅适用于 7DA7/24 或更高版本的控制器</item>
    ///         <item>特殊数据类型（如 IgnoreMacro、IgnoreKarel）需在支持的控制器上使用</item>
    ///     </list>
    /// </remarks>
    IDataTableWrapper RegisterTask(int index = 1, TaskVarType varType = TaskVarType.Task, string key = "TASK");
}